home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / utils / unix / unzip-5.12 / ZipPorts < prev   
Text File  |  1994-08-14  |  14KB  |  279 lines
  1. __________________________________________________________________________
  2.  
  3.   This is the Info-ZIP file ZipPorts, last updated on 15 August 1994.
  4. __________________________________________________________________________
  5.  
  6.  
  7. This document defines a set of rules and guidelines for those who wish to
  8. contribute patches to Zip and UnZip (or even entire ports to new operating
  9. systems).  The list below is something between a style sheet and a "Miss 
  10. Manners" etiquette guide.  While Info-ZIP encourages contributions and 
  11. fixes from anyone who finds something worth changing, we are also aware
  12. of the fact that no two programmers have the programming style and that 
  13. unrestrained changes by a few dozen contributors would result in hideously
  14. ugly (and unmaintainable) Frankenstein code.  So consider the following an
  15. attempt by the maintainers to maintain sanity as well as useful code.
  16.  
  17. (The first version of this document was called either "ZipRules" or the
  18. "No Feelthy ..." file and was compiled by David Kirschbaum in consulta-
  19. tion with Mark Adler, Cave McNewt and others.  The current incarnation
  20. expands upon the original with insights gained from a few more years of
  21. happy hacking...)
  22.  
  23.  
  24. Summary:
  25.  
  26.   (0) The Platinum Rule:  DON'T BREAK EXISTING PORTS
  27. (0.1) The Golden Rule:    DO UNTO THE CODE AS OTHERS HAVE DONE BEFORE
  28. (0.2) The Silver Rule:    DO UNTO THE LATEST BETA CODE
  29. (0.3) The Bronze Rule:    NO FEELTHY PIGGYBACKS
  30.  
  31.   (1) NO FEELTHY TABS
  32.   (2) NO FEELTHY CARRIAGE RETURNS
  33.   (3) NO FEELTHY 8-BIT CHARS
  34.   (4) NO FEELTHY LEFT-JUSTIFIED DASHES
  35.   (5) NO FEELTHY FANCY_FILENAMES
  36.   (6) NO FEELTHY NON-ZIPFILES AND NO FEELTHY E-MAIL BETAS
  37.   (7) NO FEELTHY E-MAIL BINARIES
  38.  
  39.  
  40. Explanations:
  41.  
  42.   (0) The Platinum Rule:  DON'T BREAK EXISTING PORTS
  43.  
  44.       No doubt about it, this is the one which really pisses us off and
  45.       pretty much guarantees that your port or patch will be ignored and/
  46.       or laughed at.  Examples range from the *really* severe cases which
  47.       "port" by ripping out all of the existing multi-OS code, to more
  48.       subtle oopers like relying on a local capability which doesn't exist
  49.       on other OSes or in older compilers (e.g., the use of ANSI "#elif"
  50.       constructs, C++ comments, GNU extensions, etc.).  As to the former,
  51.       use #ifdefs for your new code (see rule 0.3).  And as to the latter,
  52.       trust us--there are few things we'd like better than to be able to
  53.       use some of the elegant "new" features out there (many of which have
  54.       been around for a decade or more).  But our code still compiles on
  55.       machines dating back even longer, at least in spirit--e.g., the AT&T
  56.       3B1 family and Dynix/ptx.  Until we say otherwise, dinosaurs are
  57.       supported.
  58.  
  59.  
  60. (0.1) The Golden Rule:  DO UNTO THE CODE AS OTHERS HAVE DONE BEFORE
  61.  
  62.       In other words, try to fit into the local style of programming--no
  63.       matter how painful it may be.  This includes cosmetic aspects like
  64.       indenting the same amount (both in the main C code and in the in-
  65.       clude files), using braces and comments similarly, NO TABS (see rule
  66.       #1), etc.; but also more substantive things like (for UnZip) putting
  67.       character strings into static (far) variables and using the LoadFar-
  68.       String macros to avoid overflowing limited MS-DOS data segments, and
  69.       using the PRINTF/FPRINTF/PUTC macros instead of the corresponding
  70.       functions so that dynamic-link-library ports are simpler.
  71.  
  72.       Note that not only do Zip and UnZip differ in these respects, so do
  73.       individual parts of each program.  While it would be nice to have
  74.       global consistency, cosmetic changes are not a high priority; for
  75.       now we'll settle for local consistency--i.e., don't make things any
  76.       worse than they already are.
  77.  
  78.       Exception (BIG exception):  single-letter variable names.  Despite
  79.       the prevailing practice in much of Zip and parts of UnZip, and de-
  80.       spite the fact that one-letter variables allow you to pack really
  81.       cool, compact and complicated expressions onto one line, they also
  82.       make the code very difficult to maintain and are therefore *strongly*
  83.       discouraged.  Don't ask us who is responsible in the first place;
  84.       while this sort of brain damage is not uncommon among former BASIC
  85.       programmers, it is nevertheless a lifelong embarrassment, and we do
  86.       try to pity the poor sod (that is, when we're not chasing bugs and
  87.       cursing him).  :-)
  88.  
  89.  
  90. (0.2) The Silver Rule:  DO UNTO THE LATEST BETA CODE
  91.  
  92.       Few things are as annoying as receiving a large patch which obviously
  93.       represents a lot of time and careful work but which is relative to
  94.       an old version of Info-ZIP code.  As wonderful as Larry Wall's patch
  95.       program is at applying context diffs to modified code, we regularly
  96.       make near-global changes and/or reorganize big chunks of the sources
  97.       (particularly in UnZip), and "patch" can't work miracles--big changes
  98.       invariably break any patch which is relative to an old version of the
  99.       code.
  100.  
  101.       Bottom line:  contact the Info-ZIP core team FIRST (via the zip-bugs
  102.       e-mail address) and get up to date with the latest code before begin-
  103.       ning a big new port.
  104.  
  105.       
  106. (0.3) The Bronze Rule:  NO FEELTHY PIGGYBACKS
  107.  
  108.       UnZip is currently ported to something like 10 operating systems
  109.       (a few more or less depending on how one counts), and each of these
  110.       has a unique macro identifying it:  AMIGA, ATARI_ST, __human68k__,
  111.       MACOS, MSDOS, OS2, NT (or WIN32), TOPS20, UNIX, VMS.  Zip is moving
  112.       in the same direction.  New ports should NOT piggyback one of the
  113.       existing ports unless they are substantially similar--for example,
  114.       Minix and Coherent are basically Unix and therefore are included in
  115.       the UNIX macro, but DOS djgpp ports and OS/2 emx ports (both of which
  116.       use the Unix-originated GNU C compiler and often have "unix" defined
  117.       by default) are obviously *not* Unix.  [The existing MTS port is a
  118.       special exception; basically only one person knows what MTS really
  119.       is, and he's not telling.  Presumably it's not very close to Unix,
  120.       but it's not worth arguing about it now.]  Along the same lines,
  121.       neither OS/2 nor Human68K is the same as (or even close to) MS-DOS.
  122.  
  123.       Bottom line:  when adding a new port (e.g., MVS), create a new macro
  124.       for it ("MVS"), a new subdirectory ("mvs") and a new source file for
  125.       OS-specific code ("mvs/mvs.c").  Use #ifdefs to fit any OS-specific
  126.       changes into the existing code (e.g., unzip.h).  If it's close enough
  127.       to an existing port that piggybacking is a temptation, define a new
  128.       "combination macro" (e.g., "MVS_UNIX") and replace the old macros as
  129.       required.  (This last applies to UnZip, at least; Jean-loup prefers
  130.       fewer macros and long #ifdef lines, so talk to him about Zip.)  See
  131.       also rule 0.1.
  132.  
  133.       (Note that, for UnZip, new ports need not attempt to deal with all
  134.       features.  Among other things, the wildcard-zipfile code in do_wild()
  135.       may be replaced with a supplied dummy version, since opendir/readdir/
  136.       closedir() or the equivalent can be difficult to implement.)
  137.  
  138.  
  139.   (1) NO FEELTHY TABS
  140.  
  141.       Some editors and e-mail systems either have no capability to use
  142.       and/or display tab characters (ASCII 9) correctly, or they use non-
  143.       standard or variable-width tab columns, or other horrors.  Some edi-
  144.       tors auto-convert spaces to tabs, after which the blind use of "diff
  145.       -c" results in a huge and mostly useless patch.  Yes, *we* know about
  146.       diff's "-b" option, but not everyone does.  And yes, we also know this
  147.       makes the source files bigger, even after compression; so be it.
  148.  
  149.       Bottom line:  use spaces, not tabs.
  150.  
  151.       Exception:  some of the makefiles (the Unix one in particular), for
  152.       which tabs are required as part of the syntax.
  153.  
  154.       Related utility programs:
  155.           Unix, OS/2 and MS-DOS:  expand, unexpand.
  156.           MS-DOS:  Buerg's TABS; Toad Hall's TOADSOFT.
  157.           And some editors have the conversion built-in.
  158.  
  159.  
  160.   (2) NO FEELTHY CARRIAGE RETURNS
  161.  
  162.       All source, doc